<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) 2015, 2016 IBM Corporation and others. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
<title>Adopting Neon (4.6) mechanisms and APIs</title>
</head>

<body>

<h1>Adopting Neon (4.6) mechanisms and APIs</h1>

<p>
  This section describes changes that are required if you are trying to change
  your 4.5 plug-in to adopt the 4.6 mechanisms and APIs.
</p>

<ol>
	<li><a href="#progress_convention">The calling conventions have changed for methods which receive a progress monitor</a></li>
	<li><a href="#SubProgressMonitor">The class SubProgressMonitor has been deprecated and replaced by the class SubMonitor</a></li>
	<li><a href="#ListenerList">ListenerList has been generified</a></li>
	<li><a href="#FullScreen">Toggling Full-Screen</a></li>
	<li><a href="#HighDPI">High-DPI icons</a></li>
</ol>

<hr>

<!-- ############################################## -->
<h2><a name="progress_convention">1. New calling convention for progress monitors</a></h2>

<p><strong>What is affected:</strong>
<p> All methods which receive an IProgressMonitor and all of their callers.</p>

<p><strong>Description:</strong>
<p>
In order to reduce boilerplate, Eclipse 4.7 will introduce a new calling convention for
methods which receive an IProgressMonitor as a parameter. In Eclipse 4.7 it will be the
caller's responsibility to invoke <code>done()</code> on IProgressMonitor rather than the
receiver. Callers can choose to use SubMonitor, which doesn't required the use of
<code>done()</code>. This means that - in practice - most
invocations of <code>done()</code> will be deleted along with their surrounding try/catch blocks.
<p>
Clients should not remove the boilerplate yet. For now, any method that previously
received an IProgressMonitor and invoked done() on it should continue to do so.
<p>
Methods which obtain their own top-level progress monitors rather than receiving one as a
parameter are now responsible for invoking done() on those monitors. Technically, they were
always responsible for doing this, but some of them didn't do so because any method they
passed it to would have invoked done() on their behalf. Now this will matter and the methods
will need to be changed. For example:

<pre>
// Before:
public void doSaveAs() {
  IProgressMonitor monitor= getProgressMonitor();
  performSaveAs(monitor);
}
</pre>

<pre>
// After:
public void doSaveAs() {
  IProgressMonitor monitor= getProgressMonitor();
    try {
      performSaveAs(monitor);
    } finally {
      monitor.done();
    }
}
</pre>

<p>
Fortunately there are few of these methods and they are easy to find.
<p>
<strong>Action required:</strong>
<ul>
<li>Open the call hierarchy view on StatusLineManager#getProgressMonitor().</li>
<li>Ensure that all callers of these methods contain a finally block that
    invokes done (as in the doSaveAs() example, above).</li>
<li>Open the type hierarchy of IProgressMonitor. Look for progress monitors which do something in
    their done() method besides reporting work, setting a task name, or calling done on another
    monitor. SubMonitor can be ignored. Monitors which set a control's visibility or deallocate a
    resource in their done() method must not be ignored.</li>
<li>Use the call hierarchy view to locate every place that instantiates or accesses an instance of
    one of those classes. Ensure that those access points contain a try/finally block that invokes done().</li>
</ul>

<p><strong>More Information:</strong>
<p>
See <a href="https://eclipse.org/articles/Article-Progress-Monitors/article.html" target="_blank">this article</a> for
more examples of how to use progress monitors with the new calling convention. Background and discussion
about this change <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=487372" target="_blank">can be found here.</a>

<!-- ############################################## -->
<h2>2. <a name="SubProgressMonitor">SubProgressMonitor has been deprecated</a></h2>
<p><strong>What is affected:</strong> Clients that refer to <code>org.eclipse.core.runtime.SubProgressMonitor</code>.</p>
<p><strong>Description:</strong>
<code>org.eclipse.core.runtime.SubProgressMonitor</code> has been deprecated and replaced by
<code>org.eclipse.core.runtime.SubMonitor</code>.</p>
<p><strong>Action required:</strong></p>
<ul>
<li>Calls to IProgressMonitor.beginTask on the root monitor should be replaced by a call to
SubMonitor.convert.</li>
<li>Keep the returned SubMonitor around as a local variable and refer to it instead of the
root monitor for the remainder of the method.</li>
<li>All calls to SubProgressMonitor(IProgressMonitor, int) should be replaced by calls to
SubMonitor.split(int).</li>
<li>If a SubProgressMonitor is constructed using the SUPPRESS_SUBTASK_LABEL flag, replace it
with the two-argument version of SubMonitor.split(int, int) using SubMonitor.SUPPRESS_SUBTASK
as the second argument.</li>
<li>It is not necessary to call done on an instance of SubMonitor.</li>
</ul>

<p><strong>Example:</strong>

</p>
Consider the following example:
<pre>
     void someMethod(IProgressMonitor pm) {
        pm.beginTask("Main Task", 100);
        SubProgressMonitor subMonitor1= new SubProgressMonitor(pm, 60);
        try {
           doSomeWork(subMonitor1);
        } finally {
           subMonitor1.done();
        }
        SubProgressMonitor subMonitor2= new SubProgressMonitor(pm, 40);
        try {
           doSomeMoreWork(subMonitor2);
        } finally {
           subMonitor2.done();
        }
     }
</pre>
The above code should be refactored to this:
<pre>
     void someMethod(IProgressMonitor pm) {
        SubMonitor subMonitor = SubMonitor.convert(pm, "Main Task", 100);
        doSomeWork(subMonitor.split(60));
        doSomeMoreWork(subMonitor.split(40));
     }
</pre>

<!-- ############################################## -->
<h2>3. <a name="ListenerList">ListenerList has been generified</a></h2>
<p><strong>What is affected:</strong> Clients that refer to <code>org.eclipse.core.runtime.ListenerList</code>.
</p>
<p><strong>Description:</strong>
<code>org.eclipse.core.runtime.ListenerList</code> has been generified to offer compile-time type
safety, to simplify client code, and to avoid giving clients access to an internal array.
<code>ListenerList&lt;E&gt;</code> now implements <code>Iterable&lt;E&gt;</code>.
</p>
<p><strong>Action required:</strong>
Clients should:
</p>
<ul>
<li>add type arguments to their references to ListenerList</li>
<li>convert usages of <code>#getListeners()</code> to an enhanced 'for' loop,
thereby taking advantage of the type-safe <code>#iterator()</code>.</li>
</ul>

<!-- ############################################## -->
<h2>4. <a name="FullScreen">Toggling Full-Screen command</a></h2>
<p><strong>What is affected:</strong> Any code using the OS&nbsp;X-specific
<code>org.eclipse.ui.cocoa.fullscreenWindow</code> command.

<p><strong>Description:</strong> Eclipse Platform 4.2 introduced
an OS&nbsp;X-specific command to toggle full-screen mode for the
current window called <code>org.eclipse.ui.cocoa.fullscreenWindow</code>,
bound to Command-Ctrl-F.  In 4.6 we introduced a cross-platform
command to toggle full-screen called
<code>org.eclipse.ui.window.fullscreenmode</code> (bugs <a
href="https://bugs.eclipse.org/489087" target="_blank">489087</a>, <a
href="https://bugs.eclipse.org/491572" target="_blank">491572</a>).  As a result,
we have two "Toggle Full Screen" commands on OS&nbsp;X, and both
appear in the <em>Quick Access</em>.  The use of
<code>org.eclipse.ui.cocoa.fullscreenWindow</code> is now deprecated,
and developers should use the
<code>org.eclipse.ui.window.fullscreenmode</code> command instead.
</p>

<p><strong>Action required:</strong>
Clients should convert usages to the
<code>org.eclipse.ui.window.fullscreenmode</code> command.</p>

<!-- ############################################## -->
<h2>5. <a name="HighDPI">High-DPI icons</a></h2>
<p><strong>What is affected:</strong> Products that use bitmap images.

<p><strong>Description:</strong> On high-DPI screens, SWT now automatically
scales images that have been created by one of the traditional constructors
of <code>org.eclipse.swt.graphics.Image</code>. To avoid blurry images,
clients can use one of these constructors:
<ul><li><code>Image(Device, ImageFileNameProvider)</code></li>
    <li><code>Image(Device, ImageDataProvider)</code></li>
</ul>
<p>
JFace-based applications that use the standard<br>
<code>org.eclipse.jface.resource.ImageDescriptor#createFromURL(URL)</code><br>
API to create icon images already support high-DPI icons out of the box:
<p>
Just append "@2x" to the file name and place the high-DPI icons
into the same folder as the original icon. If you use OSGi bundles, you can also put the icons into a fragment
that contains the same folder structure.
<p>
Example:<br>
100%: newclass_wiz.png<br>
200%: newclass_wiz@2x.png

<p><strong>Action required:</strong>
In JFace applications, add "@2x" icons. In SWT applications, use the new Image constructors.</p>

</body>
</html>
